Raw Matters
Minmatar
   |
Posted - 2011.09.02 12:29:00 -
[1]
Just started working with the new Eve API and the first thing I had to notice was... a complete lack of documentation. The page www.eveonline.com/api/doc/ is actually blank, the wiki.eveonline.com/en/wiki/EVE_API_Functions site is well hidden and while well documented does not refer to the new API key system. I actually had to search the forum and blog to find the new vCode parameter and how to use it. Please fix that, otherwise people with good ideas might get stuck on step one. 
After taking that hurdle I was finally able to get some results. My impression so far is that the Eve API is very nice in general but lacks or is flawed in some details.
- No cross-domain requests are supported which makes it impossible to create browser based tools. Please add a JSONP parameter (like callback="...") that returns the response formatted according to the JSONP definition. This would make a lot of JavaScript developers happy.
- Only XML is requestable, which is ok but JSON would be a really nice to have.
- The results are very talkative, many parts of the content aren't really required or could be shortened, they look very much like a plain data dump. Lets take this example result:
 Quote:
<eveapi version="2">
<currentTime>
2011-09-02 11:22:18
</currentTime>
<result>
<rowset name="characters" key="characterID" columns="name,characterID">
<row name="Raw Matters" characterID="1753964596"/>
</rowset>
</result>
<cachedUntil>
2011-10-02 11:22:18
</cachedUntil>
</eveapi>
It does contain all required information, but actually I only wanted the row elements. A much more compact while equally expressive result could look like this:
Quote:
<eveapi version="2">
<results time="2011-09-02 11:22:18" cachedUntil="2011-10-02 11:22:18">
<character name="Raw Matters" id="1753964596"/>
</results>
</eveapi>
A similar example would be the market order list: I am probably only interested in recent market orders or those of a specific state, but there are no parameters to limit/filter the response. This does not only cause a lot of unnecessary traffic to be send over the line, but requires the client to parse a lot of noise as well just to get to the interesting part.
- In addition to this as a best practice it has been established to put the API version number into the URL instead of the response. This serves two purposes: for once on each version update all caches are automatically clean (as the URL is different) and for second any client can continue to send calls to a version this client knows it is compatible to until this client has been updated to the new version (aka you don't break stuff). Example: https://api.eveonline.com/v2/eve/CharacterID.xml.aspx?names=Raw%20Matters
- The response contains no caching header information although the caching time is very well defined by CCP. Something like "max-age: 3600" or "Expires: ..." would be great and would take some load of your servers as well.
- There is no XML schema defined for the response and there is none linked in the response. While this is not necessary for a response to be parsed, it would help you and testers a lot to check whether or not the response is actually grammatically correct. In addition many XML parsers (like Java) offer an automated parsing code generation if such XSD is defined.
- While the new API keys are from a developer perspective very nice, they are a hassle to use for users that do not have a technical background. I suggest to create template permission settings to help these users like "Skill & Learning", "Market data", "Corporation information".
|